Magic-API管理系统使用说明

系统版本:1.2.1 (20240105)

文档创建日期:2023/11/28

文档最后更新:2024/01/05

一、系统部署

基础软件部署

  1. 安装配置Mysql 5.7或更新版本(安装配置过程不在此详述);

    • 配置Mysql参数,解决同步大数据接口时报错的问题:

    • 初始化数据,客户端工具连接Mysql:

      在Mysql系统中,创建数据库:

      属性
      Database Namemagic
      Character setutf8mb4
      Collationutf8mb4_general_ci

      打开magic数据库,在查询窗口中执行initMagicApi.sql脚本,初始化数据;

  2. 安装配置Redis 6.2.x或更新版本(安装配置过程不在此详述);

  3. 安装配置JDK 1.8.0_291或更新版本(安装配置过程不在此详述);

    • 启用256位以上的密码策略强度:

      将#crypto.policy=unlimited前面的 # 号去掉,变成:

部署步骤(Linux)

  1. 创建目录:

  2. 上传下列文件至/usr/local/magic-api目录下:

    序号文件名类型说明
    1madmin.shshell脚本启动/停止Magic-API的Linux脚本
    2application.yml
    application-prod.yml
    application-shiro.yml
    application-static.yml
    logback-spring.xml
    magic-editor-config.js
    配置文件程序运行的配置项信息
    3license.lic
    publicCerts.keystore
    许可证书授权管理的许可证书文件
    4magic-api.jarjar文件程序文件
    5initMagicApi.sqlsql文件初始化系统的sql语句
    6images目录下的
    loginbackground.jpeg
    loginlogo.png
    background.jpeg
    图片可根据需要替换图片
    loginbackground.jpeg:系统登录首页背景图片
    loginlogo.png:系统登录首页logo图片
    background.jpeg:系统主界面首页背景图片
  3. 修改配置信息

    • 配置文件信息请参见“系统配置文件”部分说明;

  4. 修改文件可执行权限:

  5. 启动系统:

    • 启动Magic-API管理系统:

    • 停止Magic-API管理系统:

部署步骤(Windows)

  1. 创建目录:

  2. 上传下列文件至c:\software\magic-api\目录下:

    序号文件名类型说明
    1admagicstart.bat
    bat脚本启动/停止Magic-API的Windows脚本
    2application.yml
    application-prod.yml
    application-shiro.yml
    application-static.yml
    logback-spring.xml
    magic-editor-config.js
    配置文件程序运行的配置项信息
    3license.lic
    publicCerts.keystore
    许可证书授权管理的许可证书文件
    4magic-api.jarjar文件程序文件
    5initMagicApi.sqlsql文件初始化系统的sql语句
    6images目录下的
    loginbackground.jpeg
    loginlogo.png
    background.jpeg
    图片文件可根据需要替换图片
    loginbackground.jpeg:系统登录首页背景图片
    loginlogo.png:系统登录首页logo图片
    background.jpeg:系统主界面首页背景图片
  3. 修改配置信息

    配置文件信息请参见“三、系统配置文件”部分说明;

  4. 修改文件可执行权限:

    确保执行命令的用户对magic-api.jar有读取和执行的权限。

  5. 启动系统:

    • 启动Magic-API管理系统:

    • 停止Magic-API管理系统:

      关闭命令行窗口即可;

二、系统登录

登录地址

http://127.0.0.1:8888/index

用户名/密码

用户名: admin密 码:admin123

注意事项

  1. 请使用Chrome/Firefox/Edge浏览器访问,部分功能页面不支持IE系列;

  2. 为保证正常访问系统,请在服务器端放行防火墙对端口的访问权限;

  3. 如果Redis服务器和Magic-API服务器不在同一台机器上,请在服务器端放行防火墙对Redis服务器端口的访问权限;

三、系统配置文件

sh/bat脚本文件

对于Linux系统,修改madmin.sh,用记事本编辑脚本文件,将其中的JAVA_TOP路径修改为实际jre/jdk安装的路径:

对于Windows系统,修改admagicstart.bat,用记事本编辑脚本文件,将其中的JAVA_TOP路径修改为实际jre/jdk安装的路径:

yml配置文件

  1. 建议只修改application-prod.yml文件,其它yml文件保持默认配置;

  2. 配置测试环境时,可将application-prod.yml命名为application-dev.yml,同时修改application.yml中active: prod为active: dev即可;

  3. 注意Linux系统路径使用/正斜杠,Windows系统路径使用\反斜杠;

js配置文件

magic-editor-config.js,前端运行需要配置信息,一般修改baseURL、serverURL、title三个信息即可;

四、系统说明

本系统是在原开源magic-api接口快速开发框架的基础上,保留其强大、易用的特性,针对企业权限管控需求及实际项目需要,增加系统用户管理、角色管理、菜单管理、安全性管理、日志管理等功能,整合形成Magic-API接口管理系统。

logo-magic-api

 

 

magic-api接口快速开发框架的特点:

基于Java的接口快速开发框架,编写接口将通过magic-api提供的UI界面完成,自动映射为HTTP接口,无需定义Controller、Service、Dao、Mapper、XML、VO等Java对象即可完成常见的HTTP API接口开发

magic-api官网快速入门、基础教程链接:

https://www.ssssssss.org/magic-api/pages/quick/intro/

接口访问权限控制-前端界面

本系统通过“用户<->角色<->菜单<->接口”实现用户接口权限管控;用户通过前端UI界面在magic-api平台创建的分组、接口,由系统自动同步到菜单项目中;角色授权时通过勾选对应接口,再分配角色至用户,即可实现对用户前端界面操作接口的权限控制:

image-20231129114727977image-20240105120116712

 


用户自己在magic-api创建成功的分组、接口,无需由管理员额外授权,可由本人即时获得对该分组/接口查看/编辑管理的权限;

分配了“[内置]Magic接口同目录查看”角色的用户,如果拥有某个目录的访问权限,则自动获得其他用户在此目录下创建的接口查看权限(注意不能自动获得此目录下子目录的查看权限);

image-20240105120034662

接口访问权限控制-第三方调用

此模式基于Oauth2.0的客户端凭据机制;这种场景下的授权,便是客户端凭据许可,第三方软件可以直接使用注册时的 client_id 和 client_secret 来换回访问令牌 token 的值。其原理如下:

image-20231129123205659

本系统通过“Client<->角色<->菜单<->接口”实现Client ID接口权限控制;在角色定义界面绑定角色与菜单项目(即接口)的关系 ,再分配角色至指定的Client ID,即可实现对Client ID访问接口的权限控制:

image-20231129123718020image-20231129123814622image-20231129123857103

客户端凭据访问接口步骤:

  1. 获取动态token(以账号dms-client为例):

    Keyvalue
    client_iddms-client
    client_secret668f73c4-ec2e-8745-0c91-1194133e958b
    grant_typeclient_credentials

    接口访问信息:

    参数名参数值 
    接口地址http://127.0.0.1:8888/oauth2/client_token 
    调用方式POST 
    调用参数client_id:dms-client
    client_secret:668f73c4-ec2e-8745-0c91-1194133e958b
    grant_type:client_credentials
     
    encTypeapplication/x-www-form-urlencoded 

    调用接口成功后,返回结果data.client_token值即为获得的动态token;

  2. 调用接口:

    调用接口时,在Headers中添加access_token参数(POST和GET方式相同),这里的参数值即为上一步获得的动态token:

    参数名参数值
    access_tokenmPx6cs5SVPwLznivShOfhSNvjMqcjRYmhDq4irxqKejxW3JNHrwSYNDcEDnl
image-20231129144936901image-20231129145020185

 

匿名模式&静态token

针对单个接口,在接口配置选项处设置允许匿名访问(anonymous=true):

image-20231129143229185image-20231129145841763image-20231129150021433

接口日志查询

定时任务

本系统提供定时任务管理,可实现对接口的调度运行,[系统监控->定时任务]:

image-20231129150509934

配置定时任务调用Magic-API接口时,调用目标字符串各参数的含义:

参数项参数说明说明
Bean调用名称magicTask.run固定值
第一个参数接口调用方式接口的调用方式,get/post
第二个参数接口相对路径这里填写接口的相对路径,如interface/test/queryInfo;
相对路径的获取方式:在Magic-API接口管理界面,鼠标选择接口,右键->复制相对路径
image-20231129151344715
第三个参数接口参数要传入接口的参数;
POST调用 :{body:map},body为固定变量名,map为接口要处理的实际Json参数;
GET调用:{paraname1:paravalue1, paraname2:paravalue2,…}
第四个参数接口日志记录是否在[接口管理->接口日志->接口调度]记录接口调度日志信息;
true:记录接口调度日志;
false:不记录接口调度日志;
注意:不管参数如何设置,在定时任务管理界面的日志按钮查看页面,都可查看接口的调度日志信息;

执行策略详解:

立即执行:(所有misfire的任务会马上执行)打个比方,如果9,10点的任务都misfire了,在10:15系统恢复之后,9点,10点的misfire会马上执行执行一次:(会合并部分的misfire,正常执行下一个周期的任务)假设9,10点的任务都misfire了,系统在10:15分起来了。只会执行一次misfire,下次正点执行。放弃执行:(所有的misfire不管,执行下一个周期的任务)

image-20240105120452698

接口选项说明

系统中内置了接口选项,以下是对各选项作用的说明:

选项Key选项Value选项描述说明
logtrue/false/dbtrace是否记录日志(true或留空:记录;false:不记录;dbtrace:记录日志及报文内容)未配置或log=true,系统记录接口运行日志;日志信息同时存放在/logs/目录下的info/warn/debug/error子目录的log文件中,以及log数据表中;
log=false,系统不记录接口运行日志,针对频繁调用的基础数据接口,如果要避免接口调度过程中大量的日志数据产生,可通过log=false设置来屏蔽;
log=dbtrace,系统记录日志结果时,不仅包含log=true参数时的log文件和log数据表,还会将报文参数和返回结果记录在log数据明细表中,此选项会造成数据表空间较快的增长,故建议只在特殊场景需要调试接口时快速追踪日志信息时设置,调试完毕需要关闭切换回log=true;
ip允许调用本接口的远程机器IP白名单IP白名单(多个逗号分隔,支持-和/组合)比如在特定场景下,本接口只允许定时任务调度,不允许其它远端系统调用,可设置ip=127.0.0.1;
示例:
192.168.1.1;192.168.3.17-192.168.3.38;192.168.4.0/24
onlinetrue/false空或true:接口在线;false:接口下线,只允许UI端调用未配置或online=true,接口允许前端界面调用和第三方系统远程调用;
online=false,接口只允许前端界面调用,不允许第三方系统远程调用;
enabled_static_tokentrue/false接口是否启用静态token未配置或enabled_static_token=true,访问接口时需要提供静态token参数;
enabled_static_token=false,接口不启用静态token参数;
注意:接口要启用静态token,需要同时满足两个条件:
1.接口选项enabled_static_token=true;
2.系统参数sys.magic.statictoken指定非none值(静态token值);
一般来说,启用了静态token,就不需要同时启用动态token验证,此时在接口选项中,指定anonymous=true即可;
xml_param_intrue/false接口参数为xml格式未配置或xml_param_in=false,接口默认json格式报文;
xml_param_in=true,接口接受xml格式报文;
系统的处理逻辑:当指定xml_param_in=true,传入xml格式报文后,系统自动将xml报文转换为json格式的报文,此时在接口脚本中,用body接收到的即为json格式的报文;
注意此选项指定为true后,无法直接在前端界面调试,需要通过PostMAN等工具进行调用调试;
xml_resp_outtrue/false返回报文json自动转换为xml格式如果需要接口返回xml格式报文结果,配置xml_resp_out=true,系统自动将接口生成的json报文转换为xml报文,返回给调用方;
anonymoustrue/false该接口不需要登录也可访问未配置或anonymous=false,接口按照正常的客户端凭据访问权限控制;
anonymous=true,接口允许匿名访问,在第三方调用时无需提供动态token;
注意:前端调试接口时,不受此参数控制,也无需提供动态token;

参数设置说明

系统内置了参数设置,以下是对各主要参数作用的说明:

参数键名参数名称参数值参数说明
sys.magic.log.maxdaysmagic:接口日志最大保留天数30系统保留接口日志的最大天数;超过此数字的接口日志将被定期清除;目前系统设置为每天5:00运行清除任务;清除的日志包括存放在服务器路径上的log文件,以及存放在数据库表中的log日志数据;
magic-api接口日志最大保留天数;如果参数值小于7,则系统保留7天;
sys.clientid.tokentimeoutmagic:ClientId管理-默认超时时间480000ClientId通过客户端凭据获取动态token,token默认的超时时间(单位:秒)
sys.magic.statictokenmagic:接口是否启用静态tokenNONENONE:不启用静态token;其它值:启用静态token
此选项和接口选项enabled_static_token配合使用;
sys.magic.secure.ipmagic:接口是否启用IP白名单*或ip*:允许任意IP访问;0:禁止所有IP访问; 其它值(多个用;号分隔):192.168.1.1;192.168.3.17-192.168.3.38;192.168.4.0/24
注意:此参数和接口选项ip作用不一样,此参数影响所有接口的访问,接口选项ip只影响特定接口的访问;
sys.magic.apientity.sync.statusmagic:api entity同步状态true/falsefalse:未同步; true:已同步
此参数设置为false,系统会定时(每隔2分钟扫描一次)将接口的信息完整同步到系统菜单项目中;同步后会将此标识置为true;
后续的接口变化情况(新增、更名、删除),系统会实时同步;故一般情况下,此选项只在系统初始化时设置一次为false即可;如果有特殊情况,比如后台删除了菜单项的相关数据,可以将此参数设置为false,系统重新同步。

配置文件敏感数据加密

在定义配置文件application-prod.yml时,涉及到数据库连接密码或远程推送时秘钥等敏感数据:

image-20240105121224796

可以通过加密的方式防止这些敏感数据泄露,具体操作步骤:

  1. 确定加密密钥,这里示例如:Magic123,记住这个密钥,后面在生成加密密文以及启用系统时需要;

  2. 菜单:系统工具->加密解密,打开加密解密页面:

    image-20240105121738001

     

  3. 在Jasypt加密处,密钥处输入第1步确定的加密密钥的Magic123,明文输入root,这个root是配置文件中cfg-datasource.password的密码明文,点击“加密”按钮,生成密文wUO0iddnIn49HTYhbprxLg==;

    注意:相同密钥和明文,生成的密文不是唯一的,每点击一次加密,生成的密文都会变化,这里取任意一次生成的密文都可以。

  4. 将生成的密文用如下格式替换原来的root密码:ENC(密文)

    image-20240105122323303

     

  5. 保存配置文件,用./madmin.sh stop退出系统;用如下命令启动系统:

     

  6. 系统提示输入密码:

    image-20240105122648177

     

  7. 这里输入第1步确定的加密密钥Magic123,该密钥也是对密码加密后密文的解密密钥。确认系统启动:

    image-20240105122836352

     

数据源扩展

magic-api接口平台支持多数据源,包括但不限于(只要符合jdbc规范的都可以)以下数据库,如:

MySQL、MariaDB、Oracle、DB2、PostgreSQL、SQLServer、MongoDB

其它如国产的达梦数据库、涛思数据库等也支持;

本系统内置了MySQL、Oracle、PostgreSQL、SQLServer、MongoDB数据库的驱动,开箱即用。其它数据库需要根据不同版本集成对应jdbc驱动文件才可使用。

存储过程调用

本系统对magic-api做了扩展,可支持基础数据类型参数的存储过程调用:

参数类型传参方式示例
IN@{参数名(参数值), 字段类型}@{p_batch_id(p_batch_id),VARCHAR}
OUT@{参数名,字段类型}@{x_return_code, VARCHAR}
IN OUT@{参数名(参数值), 字段类型}@{x_return_msg(x_message),VARCHAR}
image-20231129160927670

 

XML报文支持

本系统对接口调用做了扩展,支持调用时XML报文参数;注意这不是基于XML的WebService服务,只是支持XML数据的HTTP调用;

image-20231129152703055image-20231129152754583

传入XML参数时,前端界面无法直接调试,可通过PostMAN等工具进行测试;

image-20231129160114305